Migrate from Zulu Discovery API to Azul Metadata API by jameswald · Pull Request #1010 · actions/setup-java

jameswald · 2026-05-29T00:30:42Z

Used Claude Sonnet 4.6 to implement https://docs.azul.com/core/detailed/metadata-api-migration.html. If it's way off the mark then we can close it but if it's salvageable then please feel free to push any necessary commits on top of what is already done although I believe the changes I've made for this PR are complete.

Summary

Migrates the zulu distribution from the deprecated Zulu Discovery API (https://api.azul.com/zulu/download/community/v1.0/bundles/) to the new Azul Metadata API (https://api.azul.com/metadata/v1/zulu/packages/).

Background

The old Zulu Discovery API was returning HTTP 520 errors for a few hours, breaking all distribution: zulu workflows. Since the beginning of 2023 Azul has recommended the Metadata API and published a migration guide.

Changes

`src/distributions/zulu/models.ts`

Updated IZuluVersions to match the new API response shape:

id: number → package_uuid: string
url → download_url
jdk_version → java_version
zulu_version → distro_version
Added latest: boolean and availability_type: string

`src/distributions/zulu/installer.ts`

New API base URL: https://api.azul.com/metadata/v1/zulu/packages/
Renamed query parameters: ext → archive_type, bundle_type → java_package_type, javafx → javafx_bundled
Removed hw_bitness and abi query parameters (no longer part of the API)
Added availability_types=ca to restrict to free community builds
Pagination: the new API is paginated; added a loop that iterates through all pages until an empty page is returned
Simplified getArchitectureOptions(): now returns a plain string instead of {arch, hw_bitness, abi}. Architecture mapping: x64 → x64, x86 → x86, arm64/aarch64 → aarch64
Linux platform: returns linux_glibc instead of linux to exclude musl packages, which standard GitHub-hosted runners do not use
Fixed a typo: win_aarhc4 → win_aarch64

`README.md`

Updated the architecture-mapping note to reflect the new API's conventions (arm64 → aarch64).

Test fixtures and tests

Updated all three fixture files (zulu-releases-default.json, zulu-linux.json, zulu-windows.json) to use the new field names
Updated URL assertions in all three installer test files to match the new endpoint and parameter names
Updated getArchitectureOptions test cases to expect strings instead of objects
Removed the DistroArch type (no longer needed)

Related issue

Fixes #795

Check list

Documentation updated (README.md)
Tests added/updated to cover the changes

Fixes #795
Fixes #636

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Migrates the Zulu (Azul) distribution from the deprecated zulu/download/community/v1.0 API to the new metadata/v1/zulu/packages API, updating request parameters, response model fields, and architecture mapping accordingly.

Changes:

Switched API endpoint and renamed query parameters (e.g., ext → archive_type, bundle_type → java_package_type, javafx → javafx_bundled); replaced hw_bitness/abi with a single arch value and added availability_types, page, page_size parameters.
Updated IZuluVersions model to use new field names (package_uuid, download_url, java_version, distro_version, latest, availability_type).
Updated tests and fixture data to align with the new API contract; updated README note about arch mapping.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/distributions/zulu/models.ts	Updated `IZuluVersions` interface to new Azul Metadata API schema.
src/distributions/zulu/installer.ts	Updated request URL/params, response field references, and simplified `getArchitectureOptions` to return a single string.
tests/distributors/zulu-installer.test.ts	Updated expected URLs and arch mapping assertions for macOS.
tests/distributors/zulu-linux-installer.test.ts	Updated expected URLs and arch mapping for Linux.
tests/distributors/zulu-windows-installer.test.ts	Updated expected URLs and arch mapping for Windows.
tests/data/zulu-windows.json	Regenerated fixture to match new API response schema.
tests/data/zulu-linux.json	Regenerated fixture to match new API response schema.
tests/data/zulu-releases-default.json	Regenerated fixture to match new API response schema.
README.md	Updated note about Zulu architecture mapping.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

jameswald · 2026-05-29T01:23:11Z

+      `archive_type=${extension}`,
+      `java_package_type=${bundleType}`,
+      `javafx_bundled=${javafx}`,
      `arch=${arch}`,
-      `hw_bitness=${hw_bitness}`,
      `release_status=${releaseStatus}`,
-      abi ? `abi=${abi}` : null,
-      features ? `features=${features}` : null
-    ]
-      .filter(Boolean)
-      .join('&');
+      `availability_types=ca`,
+      `page=1`,
+      `page_size=1000`
+    ].join('&');


This is beyond me so here's what Claude output in response to this comment:

⏺ The live API response tells the full story. All 5 results with javafx_bundled=true have -fx- in their filenames (e.g., zulu26.30.11-ca-fx-jdk26.0.1-linux_x64.tar.gz), confirming the filter works correctly.

The Copilot comment is not a legitimate issue. Here's why:

The reviewer is applying old-API logic to the new API. In the old API (/zulu/download/community/v1.0/bundles/), you needed two separate parameters to get JavaFX bundles:

javafx=true

features=fx

In the new Metadata API (/metadata/v1/zulu/packages/), javafx_bundled is a dedicated, purpose-built boolean field that directly filters for JavaFX-bundled packages — it's not an alias for javafx; it's an entirely different parameter on a different API. The live API confirms: passing javafx_bundled=true returns only packages whose names contain -fx-.

There's no features parameter on the new Metadata API at all — it's not just that we dropped it, it doesn't exist in the new API. Adding features=fx to the new URL would likely be ignored or cause an error.

The tests were correctly updated to match the new API's behavior, not to hide a regression.

jameswald · 2026-06-08T18:49:07Z

Unintentionally implemented many of the same changes from #998 although the scope of this PR is a bit narrower.

Fold CRaC-related work into the Zulu metadata API migration by wiring crac_supported query handling, extending Zulu package docs, and updating installer tests for jdk+crac/jre+crac behavior. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Stop paginating on a short page to avoid an extra empty request - Guard against undefined results (not just null) - Cap iterations at 100 pages and warn if the limit is hit to prevent a runaway loop if the API misbehaves Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

jameswald mentioned this pull request May 29, 2026

Migrate to new Azul metadata API (from Zulu Discovery API) #795

Open

jameswald marked this pull request as ready for review May 29, 2026 00:46

jameswald requested a review from a team as a code owner May 29, 2026 00:46

Copilot AI review requested due to automatic review settings May 29, 2026 00:46

Copilot AI reviewed May 29, 2026

View reviewed changes

jameswald changed the title ~~Use Azul metadata API~~ Migrate from Zulu Discovery API to Azul Metadata API May 29, 2026

jameswald force-pushed the azul-metadata-api branch from df4cd23 to 874ffb6 Compare May 29, 2026 11:44

brunoborges added feature request New feature or request to improve the current logic distribution JDK distribution/version/source support labels Jun 22, 2026

brunoborges mentioned this pull request Jun 22, 2026

Migrate Zulu distribution to new metadata API with CRaC support #998

Closed

jameswald and others added 7 commits June 22, 2026 14:14

Use Azul metadata API

73c0003

Document arm64 -> aarch64 mapping in README.md

9b71446

Paginate through all available versions

5130540

Fix typo: win_aarhc4

47eb437

Only query for linux_glibc packages

7793aaa

brunoborges force-pushed the azul-metadata-api branch from ab42a5b to 4c33a67 Compare June 22, 2026 18:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate from Zulu Discovery API to Azul Metadata API#1010

Migrate from Zulu Discovery API to Azul Metadata API#1010
jameswald wants to merge 7 commits into
actions:mainfrom
jameswald:azul-metadata-api

jameswald commented May 29, 2026 •

edited by brunoborges

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

jameswald May 29, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jameswald commented Jun 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

jameswald commented May 29, 2026 • edited by brunoborges Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Background

Changes

src/distributions/zulu/models.ts

src/distributions/zulu/installer.ts

README.md

Test fixtures and tests

Related issue

Check list

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

jameswald May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jameswald commented Jun 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jameswald commented May 29, 2026 •

edited by brunoborges

Loading

`src/distributions/zulu/models.ts`

`src/distributions/zulu/installer.ts`

`README.md`

jameswald May 29, 2026 •

edited

Loading